package com.clark.io;

import java.io.IOException;
import java.io.InputStream;
import java.io.Serializable;
import java.util.UUID;

/**
 * An input stream decorator that tags potential exceptions so that the stream
 * that caused the exception can easily be identified. This is done by using the
 * {@link TaggedIOException} class to wrap all thrown {@link IOException}s. See
 * below for an example of using this class.
 * 
 * <pre>
 * TaggedInputStream stream = new TaggedInputStream(...);
 * try {
 *     // Processing that may throw an IOException either from this stream
 *     // or from some other IO activity like temporary files, etc.
 *     processStream(stream);
 * } catch (IOException e) {
 *     if (stream.isCauseOf(e)) {
 *         // The exception was caused by this stream.
 *         // Use e.getCause() to get the original exception.
 *     } else {
 *         // The exception was caused by something else.
 *     }
 * }
 * </pre>
 * <p>
 * Alternatively, the {@link #throwIfCauseOf(Throwable)} method can be used to
 * let higher levels of code handle the exception caused by this stream while
 * other processing errors are being taken care of at this lower level.
 * 
 * <pre>
 * TaggedInputStream stream = new TaggedInputStream(...);
 * try {
 *     processStream(stream);
 * } catch (IOException e) {
 *     stream.throwIfCauseOf(e);
 *     // ... or process the exception that was caused by something else
 * }
 * </pre>
 * 
 * @see TaggedIOException
 * @since Commons IO 2.0
 */
public class TaggedInputStream extends ProxyInputStream {

    /**
     * The unique tag associated with exceptions from stream.
     */
    private final Serializable tag = UUID.randomUUID();

    /**
     * Creates a tagging decorator for the given input stream.
     * 
     * @param proxy
     *            input stream to be decorated
     */
    public TaggedInputStream(InputStream proxy) {
        super(proxy);
    }

    /**
     * Tests if the given exception was caused by this stream.
     * 
     * @param exception
     *            an exception
     * @return <code>true</code> if the exception was thrown by this stream,
     *         <code>false</code> otherwise
     */
    public boolean isCauseOf(Throwable exception) {
        return TaggedIOException.isTaggedWith(exception, tag);
    }

    /**
     * Re-throws the original exception thrown by this stream. This method first
     * checks whether the given exception is a {@link TaggedIOException} wrapper
     * created by this decorator, and then unwraps and throws the original
     * wrapped exception. Returns normally if the exception was not thrown by
     * this stream.
     * 
     * @param throwable
     *            an exception
     * @throws IOException
     *             original exception, if any, thrown by this stream
     */
    public void throwIfCauseOf(Throwable throwable) throws IOException {
        TaggedIOException.throwCauseIfTaggedWith(throwable, tag);
    }

    /**
     * Tags any IOExceptions thrown, wrapping and re-throwing.
     * 
     * @param e
     *            The IOException thrown
     * @throws IOException
     *             if an I/O error occurs
     */
    @Override
    protected void handleIOException(IOException e) throws IOException {
        throw new TaggedIOException(e, tag);
    }

}
